Skip to content

Polished README for Better First Impressions #39262

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

NirajDN
Copy link

@NirajDN NirajDN commented Jul 11, 2025

github:-NirajDN

Why:

Improving the readability and visual clarity of the main README.md file in the GitHub Docs repo. This makes it easier for contributors, especially newcomers, to understand the structure and how to get involved.


What's being changed:

  • ✅ Refactored the main README.md for better clarity and visual structure
  • 🎯 Added emoji-enhanced headings and improved section spacing for readability
  • 🧭 Reorganized content to group related contribution topics together
  • 📚 Enhanced descriptions for subdirectories with a cleaner table layout
  • 💡 Added emphasis on contribution opportunities and support links

Check off the following:

@github-actions github-actions bot added the triage Do not begin working on this issue until triaged by the team label Jul 11, 2025
Copy link
Contributor

How to review these changes 👓

Thank you for your contribution. To review these changes, choose one of the following options:

A Hubber will need to deploy your changes internally to review.

Table of review links

Note: Please update the URL for your staging server or codespace.

This pull request contains code changes, so we will not generate a table of review links.

🤖 This comment is automatically generated.

@NirajDN NirajDN changed the title Update README.md Polished README for Better First Impressions Jul 11, 2025
@ojaswi1234
Copy link

Great changes

Copy link
Author

@NirajDN NirajDN left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review for GitHub Docs README
This README is very well-structured, engaging, and reader-friendly. It does a great job of guiding new contributors through the project with clear sections and helpful links.

What works well:

The use of emojis and icons (📘, 🛠️, 🌟, ✨, 🧩, 📜, 💬, 💖) adds personality and makes the content visually appealing without overwhelming.

Clear call-to-action sections like “Why Contribute?” and “Ways to Contribute” help motivate and inform potential contributors.

The inclusion of links to relevant resources (contributing guide, issues board, support) ensures readers know exactly where to go next.

The table summarizing the project structure is very helpful for understanding the repo at a glance.

Friendly tone throughout encourages community involvement.

@jnts1984

This comment was marked as spam.

@Sharra-writes
Copy link
Contributor

Sharra-writes commented Jul 11, 2025

@NirajDN Man, our README is just a magnet for criticism right now (not unfairly), but it's funny that I just went over this with someone else. The README is actually meant for internal use. Our public docs repo and private docs-internal repo sync several times daily, meaning that any internal-use docs we want hosted on docs-internal are also visible in the public repo. The main problem with the README is that it isn't clear that it's for internal use, which is something I want to correct, but I haven't gotten to it yet. This is our contributing doc for external contributors, but I do currently have someone else tinkering with it in an open PR, so...maybe wait to see what they do with it and what we accept before you pour a lot of time into fixing it up.

Edit to add: You might want to read through more of our documentation. We don't really use emoji, and we also have a style guide that might be helpful.

@NirajDN
Copy link
Author

NirajDN commented Jul 11, 2025

Hi @Sharra-writes , thanks so much for the context , that really helps clarify things. 🙌

I completely understand now that the current README is intended more for internal use and that the syncing between the public and internal repos makes that a bit tricky to communicate clearly. I’ll hold off on making major changes for now and keep an eye on the open PR you mentioned. Once that settles, I’d love to revisit and contribute in a way that aligns with your internal goals and the established style.

Also, I’ll make sure to go through the documentation more thoroughly and familiarize myself with the style guide ,especially around tone and the use of emojis 😅. Thanks again for pointing that out!

Let me know if there’s anything small I can help with in the meantime.

@Sharra-writes
Copy link
Contributor

Sharra-writes commented Jul 11, 2025

@NirajDN I actually do have an issue that I think would be a great first one for someone. I got the exact wording that needs to be in the relevant article, so it should be a quick fix.

If you want something a little more creative, take a look at some of our "about" articles (so any with a title starting with "about"). They've become catch-alls for information that doesn't seem to have another home instead of being what they're supposed to be: a general overview of a subject light on specifics and heavy on "why a reader should care about this product/feature." We're doing a lot of reorganization in Actions, Copilot, and Billing currently, but "about" articles in other categories are fair game if you see one you think you could help cut down.

@NirajDN
Copy link
Author

NirajDN commented Jul 11, 2025

Hi @Sharra-writes , thank you so much for sharing this , it sounds like a great opportunity to dive into something meaningful! 🙌

I’d be happy to take on the quick fix you mentioned first ,feel free to drop the link or issue details whenever you get the chance. Also, I really like the idea of revisiting and refining the “about” articles. I’ll start looking through them to spot any that might benefit from being more concise or focused on the “why it matters” angle.

Appreciate the trust and guidance ,I’m excited to contribute in a way that aligns with the broader content goals. Let me know where you'd like me to begin!!

@Sharra-writes
Copy link
Contributor

This is the article that needs the update. The section that's inaccurate is "In the blame view, revisions are excluded only if the commit introduced new lines. If the commit was the last to modify a line, it will still appear in blame." It should read

In the blame view, revisions are excluded if the commit introduced new lines or modified existing lines. If the commit was the last to modify a line, it will still appear in blame. You’ll see an “Ignoring revisions in .git-blame-ignore-revs” banner indicating that some commits may be hidden.

Issue 39078 so you can reference it in your PR, which will close it automatically when the PR is merged.

If you need guidance on how to "about" articles should look, About discussions got updated recently.

@Sharra-writes Sharra-writes added content This issue or pull request belongs to the Docs Content team and removed triage Do not begin working on this issue until triaged by the team labels Jul 11, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
content This issue or pull request belongs to the Docs Content team
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants